(ONGOING) docs: initiate docs rewrite and theme change - #905
Conversation
|
@chaws @mwasilew this just introduces the "rough-ins" for the new docs. I have only written the intro and the model under the 'guide' dir/section for now. I've categorised each doc topic by directory to make things cleaner and easier to handle. There is a theme dependency and markdown processor dependency that will need to be used to generate this. I haven't added them to requirements.txt or requierments-dev.txt. This PR can remain a staging ground until we have rewritten old docs into markdown and put them under their relevant directory then revamps can be incremental. The two deps are: sphinx_rtd_theme and recommonmark. We also may not need files like 'make.bat' so we can remove those during the rewrite. |
mwasilew
left a comment
mwasilew
left a comment
There was a problem hiding this comment.
I would very much prefer to use markdown syntax as described here https://www.markdownguide.org/basic-syntax/ and get rid of all rst bits. It's way easier to write/edit markdown than rst.
There was a problem hiding this comment.
does it need a weird number in the file name?
There was a problem hiding this comment.
it's repeated from line 24. This one is correct.
There was a problem hiding this comment.
does the github syntax work here:
https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#code
It's much more 'techwriter friendly' than rst. That's why I asked about changing to markdown.
There was a problem hiding this comment.
I would prefer hash based headings.
cb51264 to
702ca4c
Compare
|
@mwasilew rewritten in MD. There is one link that needs to be fixed at the end of model doc and other docs will be pushed soon. |
|
Hey @amrohassaan do you think this PR is close to finish? From reading the comments, it seems you were very close |
3 participants
Fixes #700 and #702